/** @file
 *
 * @addtogroup nfc_api
 *
 * @defgroup nfc_library NFC Type 2 Tag
 * @ingroup nfc_api
 * @brief @tagAPI52 Implementation of NFC Type 2 Tag.
 *
 * @defgroup nfc_lib NFC Type 2 Tag library
 * @{
 * @ingroup nfc_library
 * @brief @tagAPI52 Type 2 Tag library.
 */

#ifndef NFC_LIB_H
#define NFC_LIB_H

#include <string.h>

#define NFC_SIZEOF_INTERNAL_BYTES 10
#define NFC_MAX_PAYLOAD_SIZE 988
#define NFC_MAX_PAYLOAD_SIZE_RAW 1008 /* No NDEF-TLV and no implicit lock bytes at the end */

/** @brief Return values generated by NFC_LIB functions. */
typedef enum
{
    NFC_RETVAL_OK,
    NFC_RETVAL_ERROR,
    NFC_RETVAL_INVALID_STATE,
    NFC_RETVAL_INVALID_SIZE,
    NFC_RETVAL_INVALID_ARGUMENT
} NfcRetval;

/** @brief Events passed to the callback function. */
typedef enum
{
    NFC_EVENT_NONE,
    NFC_EVENT_FIELD_ON,
    NFC_EVENT_FIELD_OFF,
    NFC_EVENT_DATA_READ,
    NFC_EVENT_STOPPED
} NfcEvent;

typedef enum
{
    NFC_PARAM_TESTING /* Used for unit tests */
} NfcParamId;

/** \brief Callback to pass events from NFCLib to application.
 *
 * \param context    Application context for callback execution.
 * \param event      The event that occurred.
 * \param data       Data to send to the application (event specific).
 * \param dataLength Length of the data.
 */
typedef void (*NfcCallbackFunction)(void *context, NfcEvent event, const char *data, size_t dataLength);

/** \brief Function for registering the application callback for event signaling.
 *
 * The callback will be called by NFCLib to notify the application of relevant
 * events. It will be called from the HAL_NFC callback context.
 *
 * \param callback  Function pointer to the callback.
 * \param cbContext Pointer to a memory area used by the callback for execution (optional).
 *
 * \retval OK If the application callback was registered successfully. If one
 *            of the arguments was invalid, an error code is returned.
 */
NfcRetval nfcSetup(NfcCallbackFunction callback, void *cbContext);

/** \brief Function for setting an NFC parameter.
 *
 * \note Not implemented. For future use.
 *
 * This function allows to set any parameter defined as available by HAL_NFC.
 *
 * \param id         ID of the parameter to set.
 * \param data       Pointer to a buffer containing the data to set.
 * \param dataLength Size of the buffer containing the data to set.
 *
 * \retval OK If the parameter was set successfully. If one of the arguments
 *            was invalid (for example, a wrong data length), an error code
 *            is returned.
 */
NfcRetval nfcSetParameter(NfcParamId id, void *data, size_t dataLength);

/** \brief Function for querying an NFC parameter value.
 *
 * \note Not implemented. For future use.
 *
 * The queried value will be placed into the passed data buffer. If the buffer
 * is too small, maxDataLength will contain the required buffer size. If the
 * buffer is big enough, maxDataLength will contain the actual size of the
 * data.
 *
 * \param id         ID of the parameter to query.
 * \param data       Pointer to a buffer receiving the queried data.
 * \param maxDataLength Size of the buffer, receives actual size of queried data.
 *
 * \retval OK If the parameter was received successfully. If one of the arguments
 *            was invalid (for example, the buffer was too small), an error code
 *            is returned.
 */
NfcRetval nfcGetParameter(NfcParamId id, void *data, size_t *maxDataLength);

/** \brief Function for registering the payload to send on reception of a READ request.
 *
 * The payload is considered to only contain the NDEF message to deliver to a
 * reader. The required NDEF TLV will be created implicitly by NFCLib.
 *
 * The pointer to the payload must stay valid for the duration of the library
 * execution, or until it is explicitly released.
 *
 * If the pointer is not NULL, but the length is zero, the paypload is
 * considered to be an empty NDEF message.
 *
 * If a new payload is registered, the previously registered one is considered
 * released.
 *
 * Passing a NULL pointer releases the current payload without registering a
 * new one.
 *
 * If an invalid size is given (too big), the function returns with an error
 * and the currently registered payload is left unchanged.
 *
 * \param payload       Pointer to the memory area containing the payload to send.
 * \param payloadLength Size of the payload in bytes.
 *
 * \retval OK If the operation was successful. If one
 *            of the arguments was invalid, an error code is returned.
 */
NfcRetval nfcSetPayload(const char *payload, size_t payloadLength);

/** \brief Function for registering the raw payload to send on reception of a READ request.
 *
 * The payload will be delivered directly as-is to the reader, without
 * implicitly adding an NDEF TLV container. This can be used if the
 * application wants to define the TLVs itself, for example, to provide a different
 * memory layout.
 *
 * The pointer to the payload must stay valid for the duration of the library
 * execution, or until it is explicitly released.
 *
 * If a new payload is registered, the previously registered one is considered
 * released.
 *
 * Passing a NULL pointer releases the current payload, without registering a
 * new one.
 *
 * If an invalid size is given (too big), the function returns with an error
 * and the currently registered payload is left unchanged.
 *
 * \param payload       Pointer to the memory area containing the payload to send.
 * \param payloadLength Size of the payload in bytes.
 *
 * \retval OK If the operation was successful. If one
 *            of the arguments was invalid, an error code is returned.
 */
NfcRetval nfcSetPayloadRaw(const char *payload, size_t payloadLength);

/** \brief Function for registering the sequence of internal bytes.
 *
 * This refers to the first 10 bytes of the tag memory. The library will set
 * a sensible default for these bytes. The application can use this function
 * to override the default.
 *
 * Passing a NULL pointer reverts back to the default sequence.
 * The data will be copied by NFCLib, so the memory does not have to remain valid
 * after the function returns.
 *
 * \note When modifying the internal bytes, remember that they must be consistent
 *       with the NFC hardware register settings (see @ref nfc_t2t_format_internal).
 *
 * \param data       Pointer to the memory area containing the data.
 * \param dataLength Size of the data in bytes.
 *
 * \retval OK If the operation was successful. If the data was not NULL and the
 *            data length was not 10, an error code is returned.
 */
NfcRetval nfcSetInternal(const char *data, size_t dataLength);

/** \brief Function for activating the NFC frontend.
 *
 * You must call this function so that events are posted to the application
 * callback.
 *
 * \retval OK If the NFC frontend was activated successfully. If the lower layer
 *            could not be started, an error code is returned.
 */
NfcRetval nfcStartEmulation(void);

/** \brief Function for deactivating the NFC frontend.
 *
 * After calling this function, no more events will be posted to the
 * application callback.
 *
 * \retval OK If the NFC frontend was deactivated successfully.  If the lower layer
 *            could not be stopped, an error code is returned.
 */
NfcRetval nfcStopEmulation(void);

/** \brief Function for releasing the reference to the application callback.
 *
 * After calling this function, the passed callback pointer is no longer
 * considered valid.
 *
 * \retval OK This function always succeeds.
 */
NfcRetval nfcDone(void);

#endif /* NFC_LIB_H */

/** @} */
